.. _AppendixA:

Appendix A: Helper Software
===========================

The subversion/git repository contains some software packages which can be used to decode the bunches in the UDP packets received from the TiCkS. All of these may be re-implemented in whatever code the users prefers, of course. 

- TiCkS_decode: contains the routines for:
    - Decoding a bunch into individual events
    - Printing individual events or writing them to file in CDTS structure, and checking for errors
    - Reading in a configuration xml file

- TiCkS_standalone: main routine and Makefile (with some example configs) for:
    - Receiving UDP packets from a TiCkS at a given IP / Port, 
        or all TiCkS at a given Port by calling the routines in TiCkS_decode
    - Depending on the options in the configuration XML (given on command line)
        - Prints events to stdout and/or writes to file
        - Prints errors to stdout or stderr, or none
        - Prints a debug dictionary of delta Event/Busy/Time to stdout
        - Optionally correct skipped event counters

- cdtsServerSimulator:
    - Receives UDP packets from a TiCkS at a given IP / Port, or 
        all TiCkS at a given Port by calling the routines in TiCkS_decode
    - Connects to cameraServer (address given in the configuration XML on command line), and sends event in TCP/IP packets
    - If the option is chosen in the configuration XML (given on command line), prints errors to stderr
    - Optionally correct skipped event counters

Some details
------------

- Debugging lines with printing to stderr or stdout (user choice) of:
    - Events with busyFlag != busyBit
    - Events with SPI time-out
    - Events with non-monotonic event counter increase (sum of read-out + busy counters)
    - Possibility to apply error correction for non-monotonic event counter increase, if this is within a margin of error
    - (i.e. lost packets will give big jumps, which should not be corrected)

- Technical detail, the software will work correctly even for multiple TiCkS sending to a IP on multiple ports, or sending to the same port on multiple IPs
    - This is done by using a "ulhash" hash table to keep previous values of counters, timestamps for the given TiCkS IP/Port combination... a very nice and widespread package!

- Configured by some values in in the config xml file (but with a default to 0 for integer values), ``err_output`` and ``cor_margin``
    - see example below

- Completely replaced mini-xml by libxml2
    - much more standard than mini-xml (and is used by gnome)
    - easier to configure with "xml2-config" command in the Makefile

- !!! With change from mini-xml to libxml2, must add top level enclosure tags

- Moved getConfigurationFromXmlFile to TiCkS_decode
     - makes this much easier to call from other codes

Configuration XML file example:
-------------------------------

::

    <?xml version="1.0" encoding="UTF-8"?>                                                                        
    <configs>                                                                                                     
                                                                                                                  
    <cdts_server_address>10.10.3.250</cdts_server_address>                                                        
    <cdts_server_port>55501</cdts_server_port>                                                                    
                                                                                                                  
    <!-- Next two lines are ignored by ticks_standalone -->                                                       
    <camera_server_address>10.10.3.250</camera_server_address>                                                    
    <camera_server_listen_port>12345</camera_server_listen_port>                                                  
                                                                                                                  
    <!-- Note, if ucts_address is left blank, or missing, all UCTSs on the port will be received                  
    <ucts_address>10.10.3.99</ucts_address>                                                                       
    <ucts_address /> -->                                                                                          
                                                                                                                  
    <!--Event Types: 0 for all, 1 for read-out, 2 for busy-->                                                     
    <event_types>0</event_types>                                                                                  
                                                                                                                  
    <!-- Use logical values for the next three (0 = False) -->                                                    
    <print_event>0</print_event>  <!-- ATTENTION, can get lots of output to stdout ! -->                          
    <file_event>0</file_event>  <!-- gets ignored for cdtsServer, no file output for now -->                      
    <dict_debug>0</dict_debug>                                                                                    
                                                                                                                  
    <!-- This is where the error output should go:                                                                
      * 0 is stderr                                                                                               
      * <0 for no output                                                                                          
      * >0 for stdout (changed to 6, then) -->                                                                    
    <err_output>0</err_output>  <!-- gets overridden to 0/stderr for cdtsServer -->                               
                                                                                                                  
    <!-- Margin within which to correct counters                                                                  
      * <=0 for no correction                                                                                     
      * small number, to correct but avoid correcting if packets lost -->                                         
    <cor_margin>0</cor_margin>                                                                                    
                                                                                                                  
    <ts_data_path>../TiCkS_data</ts_data_path> <!-- gets ignored for cdtsServer, no file output for now -->       
                                                                                                                  
    </configs>                                                                                                    
        
*Notes:*

- Any node which isn't defined is set to a sensible default value
- The first two nodes have to be there, with relevant values
- To receive several TiCkS at once
    - then either send them to the same port and leave ucts_address blank
    - or send them to the same ucts_address and the same port
- Normal operation so far is to execute each cdtsServer with a dedicated Port all on the same machine
    - This fits well with the paradigm of having the cdtsServer being part of the camera
    - In this paradigm, it should run on the Camera Server machine, and send its UCTS-timeStamp events to the SWAT
    - Optionally sending UCTS-timeStamp events to the Camera Event Builder in parallel